docs: say a Cloud environment is protected before asking for a request - #3616

No actionable comments were generated in the recent review. 🎉

_{Comment @coderabbitai help to get the list of available commands.}

Sync path confirmed, since "merged doc fixes that never reached the live site" is the recurring failure mode this round.

.github/workflows/sync-docs.yml fires on push to main with docs/getting-started/** among its paths, and dispatches into veryfront-docs. This PR touches docs/getting-started/deploy-project.md, so the merge does trigger the sync rather than needing a manual copy.

Worth checking after merge, in order:

1. veryfront-docs receives the dispatched update to docs/code/getting-started/deploy-project.md.
2. https://veryfront.com/docs/code/getting-started/deploy-project shows an Environment access section, and a Verify it worked command containing %{http_code} %{redirect_url}.

One caveat found while reproducing: for this file the live page is currently ahead of veryfront-docs@main (live already has the Push-based flow; veryfront-docs@main still has the older short version) and behind veryfront-code@main (live still carries the pre-#3576 veryfront open verification wording). The three copies disagree in both directions, so step 2 is worth actually loading rather than inferring from step 1.

All three applied in ec5d984. Each verified against source before changing anything.

403 for signed-in non-members (P2) — correct, and it was the worst of the two failures to leave undocumented. checkProtectedProxyAccess returns 302 only while the caller is unauthenticated or its token yields no user id; isProjectMember failing returns { status: 403, message: "Access denied" } (src/proxy/proxy-access-control.ts). A signed-in non-member is exactly the reader who would blame the URL rather than the account, so the page now says a 403 means the account is wrong, not the URL, in both the Environment access section and the verification step. The test pins the sentence.

Output inside the bash fence (P2) — correct. The 302 … line would have run as a third command on paste. It is a separate text fence now.

Hostname (P1) — correct. Internal hostnames are on the AGENTS.md secret-safety list and the host was never the load-bearing part of the evidence; the 302 shape was. It is <project>.production.veryfront.com now, and the comment gained the proxy-access-control.ts pointer for the 403 path.

Re-ran the finding's own reproduction against the amended page afterwards, not just the test suite: the verification command extracted verbatim from the page still prints 302 https://veryfront.com/sign-in?from=… against a live protected environment, which is what the page now tells the reader to expect.

Both findings verified against the source before acting. Both citations are accurate; nothing to push back on.

Pushed as 6b23b36d (which also merges origin/main — the branch had gone CONFLICTING on tests/docs/guide-content.test.ts, where #3605's open --site case and this PR's protected-environment case were appended at the same spot. Both cases kept).

Finding 1 — sign-in apex depends on the deployment host

Citation confirmed. resolveSignInApex (src/proxy/proxy-access-control.ts:187) picks the apex from the request host, and buildProxyAuthRedirectUrl (:202) uses it. *.preview.veryfront.org resolves to veryfront.org, asserted at src/proxy/proxy-access-control.test.ts:102-120. The page's flat claim was wrong.

One nuance I kept the prose honest about rather than inverting the rule: isHostedProductionDeployment short-circuits before the apex loop, so *.production.veryfront.org still signs in at veryfront.com (deliberate, per the #1827 comment at :186-190). So the page does not say "the apex follows the environment's own TLD" — that would be a new false statement. It says the apex depends on the serving host, gives the two concrete cases, and tells the reader to read the printed redirect_url rather than memorise one URL. It also now explains why it matters (cookie is scoped to the issuing domain, so signing in on the wrong apex loops).

Finding 2 — no universal 200 from the environment root

Citation confirmed, and it goes one step further than the finding states. readinessRoute is null when no non-dynamic page route exists (cli/shared/deployment/deploy-project.ts:1293), and buildEnvironmentReadinessProbes returns [] for a null route (:875) — so such a deployment is verified with zero HTTP probes, which is exactly what deploy-project.test.ts:635-650 asserts (assertEquals(requests, 0)). Note the null case is broader than "API-only": a project whose only page route is dynamic (/blog/[slug]) also filters out, since the find excludes any route containing [.

"Verify it worked" now tells the reader to probe a route their project actually serves and validate that route's expected status; the sample command takes <environment-url>/<route> instead of the bare root.

The assertions, and proof they fail first

Two new cases in tests/docs/guide-content.test.ts. Taking the note about the earlier structurally-weak assertion seriously, both are pinned to structure rather than keywords:

does not promise one sign-in apex for every protected environment collects every sign-in URL the page prints and requires both apexes to be present:

const signInApexes = new Set(
  [...doc.matchAll(/https:\/\/(veryfront\.(?:com|org))\/sign-in/g)].map((m) => m[1]),
);
assertEquals(signInApexes.has("veryfront.com"), true);
assertEquals(signInApexes.has("veryfront.org"), true);

Prose naming only .com cannot satisfy this — which is the point, since the pre-existing assertStringIncludes(prose, "https://veryfront.com/sign-in") passes happily on the broken page and so could never have caught this.

does not require a 200 from the environment root to call a deploy verified pins the command shape, because a command ending at the bare environment URL is the defect:

assertStringIncludes(doc, "-w '%{http_code} %{redirect_url}\\n' <environment-url>/<route>");
assertEquals(doc.includes("-w '%{http_code} %{redirect_url}\\n' <environment-url>\n"), false);
assertEquals(prose.includes("A public environment answers `200`."), false);

Red confirmed before the fix. I restored the pre-fix page from the index and ran the file — both new cases failed, and the apex-set assertion is what fires first:

does not promise one sign-in apex for every protected environment ... FAILED (2ms)
does not require a 200 from the environment root to call a deploy verified ... FAILED (0ms)

error: AssertionError: Values are not equal.                     # signInApexes.has("veryfront.org")
error: AssertionError: Expected actual: "---\n" to contain:
  "-w '%{http_code} %{redirect_url}\n' <environment-url>/<route>"

Restoring the fixed page: ok | 1 passed (33 steps) | 0 failed.

Gates

• deno test --no-check -A tests/docs/ — 52 passed | 1 failed; the only failure is the sandboxed-network one in guide-examples.test.ts (General SOCKS server failure reaching 93.184.216.34), same environmental exclusion noted in the PR body. Identified by failure text, not by test name.
• deno fmt --check — 5007 files clean; deno lint clean.
• scripts/docs/validate-guides.ts — all guides pass (the one webhook index warning is pre-existing on main).
• scripts/lint/check-doc-links.ts — all 1233 links OK, including the #environment-access anchor the new cross-reference uses.
• Full pre-push hook green; committed and pushed with Deno 2.7.7 first on PATH.

Leaving the merge decision with you — not re-queueing.

CI follow-up: green, and one more commit.

2982e1747 — the pre-existing tells the reader a Cloud environment is protected… case still had a comment asserting the universal veryfront.com apex, which now contradicted the case sitting right below it. Comment only; the assertions are unchanged.

Flake, not a regression. The first run on this SHA came back with coverage shard 4/8, coverage gate and tests (unit) red. Those are one failure, not three — tests (unit) is the Require all unit test shards aggregator (COVERAGE_SHARDS_RESULT: failure, 3s) and coverage gate depends on the shard artifact that never uploaded.

The shard log contains no FAILED test at all. The only error is a runtime-level abort:

error: Promise resolution is still pending but the event loop has already resolved

A dangling promise, no assertion. Two independent reasons it cannot be this branch:

1. Shard 4 runs with --ignore=tests, so tests/docs/guide-content.test.ts is not in its file list. The only other file this PR touches is a Markdown page with no runtime effect — the branch contributes nothing executable to that shard.
2. The same shard-flakes-then-cascades shape shows up on main unprompted (run 31563881301, coverage shard 7/8 → coverage gate → tests (unit)), there with the separate cli/commands/skills/handler.test.ts failure.

Re-ran the failed jobs only, no code change: coverage shard 4/8, coverage gate and tests (unit) all pass. Identified by failure text rather than job name, since the aggregator name is the same whatever breaks underneath.

Now: 27 pass, 0 fail, 6 skipping. Branch is MERGEABLE again after the origin/main merge.

Still not re-queued — that call is yours.